Add a long description for GtkSettings

Among other things, the description mentions the problem in
bug 585024, that some settings may not be available before the
widget class has been realized.

diff --git a/docs/reference/gtk/tmpl/gtksettings.sgml b/docs/reference/gtk/tmpl/gtksettings.sgml
index 2a5988d23992940d70926a27d7602d67301cf123..5219c1a6c2c931ccf63bad9bbf6c975c8864b7ea 100644 (file)
--- a/docs/reference/gtk/tmpl/gtksettings.sgml
+++ b/docs/reference/gtk/tmpl/gtksettings.sgml
@@ -6,7 +6,35 @@ Sharing settings between applications
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+GtkSettings provide a mechanism to share global settings between applications.
+On the X window system, this sharing is realized by an <ulink href="http://www.freedesktop.org/wiki/Specifications/xsettings-spec">XSettings</ulink>
+manager that is usually part of the desktop environment, along with utilities
+that let the user change these settings. In the absence of an Xsettings manager,
+settings can also be specified in RC files.
+</para>
+
+<para>
+Applications can override system-wide settings with gtk_settings_set_string_property(),
+gtk_settings_set_long_property(), etc. This should be restricted to special
+cases though; GtkSettings are not meant as an application configuration
+facility. When doing so, you need to be aware that settings that are specific
+to individual widgets may not be available before the widget type has been
+realized at least once. The following example demonstrates a way to do this:
+<informalexample><programlisting>
+  gtk_init (&amp;argc, &amp;argv);
+
+  /&ast; make sure the type is realized &ast/
+  g_type_class_unref (g_type_class_ref (GTK_TYPE_IMAGE_MENU_ITEM));
 
+  g_object_set (gtk_settings_get_default (), "gtk-menu-images", FALSE, NULL);
+</programlisting></informalexample>
+</para>
+
+<para>
+There is one GtkSettings instance per screen. It can be obtained with
+gtk_settings_get_for_screen(), but in many cases, it is more convenient
+to use gtk_widget_get_settings(). gtk_settings_get_default() returns the
+GtkSettings instance for the default screen.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->